InsmEdit, the Insmouse No Yakata editor
Version 1.2
Readme file and manual

Matej Horvat
May 19, 2013

*** Introduction ***

  InsmEdit is a Windows editor for the Virtual Boy game Insmouse No Yakata.
  It can currently edit:

  * level layouts
  * level passwords
  * player starting positions and directions
  * level times
  * music selections (which music track is played on a level)
  * monsters and their positions

  It can also apply IPS patches to the game. This file describes its features
  and serves as a reference for editing the game.

  The program works with "patches", which are collections of "resources". A
  resource contains data which replaces a specific part of a game, for
  example a layout or a password. Each resource has an "index" that specifies
  what exactly it replaces. For example, each layout has its own index, as
  does each password.

*** System requirements and installation ***

  * Microsoft Windows (tested on 98 and XP)
  * 2 MB of free disk space

  To install, simply extract all the files into a folder. If you are
  upgrading from a previous version, just overwrite the old files.

  If you are using 64-bit Windows 7 and attempting to run InsmEdit gives you
  the error message

    Component 'COMDLG32.OCX' not correctly registered: file is missing or
    invalid

  try following this guide:

    http://devonenote.com/2010/02/register-comdlg32-ocx-on-x64-win7/

  (This was suggested by KR155E. Neither him nor I are involved with the
  mentioned Web site.)

  If you get the same error on 64-bit Windows Vista, a possible workaround is
  to run InsmEdit as administrator (suggested by PVB user MasterOfPuppets).

*** Managing resources ***

  Once InsmEdit is started or the "New" command is chosen from the File menu,
  a blank patch is created.

  To add a resource to the patch, choose "Add" from the Resource menu, then
  choose the kind of resource you want to add. InsmEdit will add the resource
  to the list of resources and automatically open the resource for editing.

  To remove a resource, highlight it and choose "Remove" from the Resource
  menu. You will be asked to confirm your choice.

  To open a resource for editing, highlight it and choose "Edit" from the
  Resource menu. You can also double-click it or press Enter.

*** Level layout resources ***

  A level layout is a resource that replaces the layout of corridors in the
  level.

  The index of a level layout resource specifies which layout it replaces. A
  list of layout indexes is included at the end of this document.

  Layout editing is done with the mouse. The primary mouse button places a
  tile and the secondary mouse button removes it, creating a corridor. A new
  layout is filled with walls.

  By pressing the middle mouse button or scroll wheel (whichever your mouse
  has), the position of the tile you are pointing at will be remembered. You
  can then paste it into a starting position resource or a level monster
  resource.

  Besides corridors and walls, there are three more kinds of tiles: doors,
  exits, and MWalls ("monster walls"). The latter are the same as walls, but
  monsters may break through them, creating a corridor. This can be taken
  advantage of to create secret passages and shortcuts.

  Layouts are 24 tiles wide and 24 tiles high. The size cannot be changed.
  The editor shows tile coordinates as the mouse pointer passes through them
  and can optionally show a grid to make editing easier. It can also show
  where the game will place ceiling lamps, though this is somewhat unreliable
  as the game seems to show them in front of the tile they are supposed to
  be on. Still, the feature is provided in case you want to align corridors
  to lamps. The status of this and the grid feature is preserved when editing
  different layouts.

  The layout editor can also shift layouts around on the map. Shifts are
  destructive; a row or column will be lost and a new one, filled with walls,
  will be introduced on the opposite side.

  Some notes regarding layout design:

  * Do not create open spaces or corridors wider than one tile. The game will
    run fine but you might confuse the player. The TRAP level in Example.imp
    illustrates this.
  
  * A door is just a corridor through which monsters cannot pass. Therefore,
    doors can be placed at crossroads. This will force monsters to go around
    them, but the visual effect might confuse the player. The XING level in
    Example.imp illustrates this.

  * You can use doors to create decorations which will be seen on the map
    once the player picks up the white orb. You can also use them to create
    secret passages that open when a monster destroys a MWall; the passage
    should be made entirely out of doors to prevent monsters going in and
    items being placed in the corridor - if a monster doesn't destroy the
    MWall, the player may be unable to get the key and the level will be
    impossible to finish.

  * If the player starts in a wall, it will appear as if there's a corridor
    in front of them but the game will freeze.

  * If a layout is not closed, that is, if the player can go to an edge of
    the layout, it will appear as if there is a corridor in front of them
    but if they attempt to walk outside the map, they will face a wall. The
    TRAP level in Example.imp illustrates this.

*** Level password resources ***

  A level password is the password the player can enter to quickly reach a
  particular level.

  The index of a password resource specifies which level the password applies
  to. A list of password indexes is included at the end of this document.

  Some notes regarding passwords:

  * A password must be four characters long. If it is shorter, InsmEdit will
    add "X" characters to the end to ensure that the player will be able to
    enter it.

  * It can only contain uppercase characters of the ISO Latin alphabet (which
    happens to be the English alphabet). If a password contains other
    characters, garbage will appear in place of it and it will be impossible
    to enter. InsmEdit will automatically change all lowercase characters to
    uppercase, but other characters, such as digits, will be left unchanged.

  * The new password will appear on the intermission screen, but not on the
    intermission map. The original password will appear in its place there. A
    future version of InsmEdit may also be able to edit intermission screen
    level names, since their location in ROM is known.

*** Player starting position resources ***

  A player starting position specifies where on the layout the player starts
  the level and what direction they face.

  The index of a starting position resource is the same as that of a password
  resource. A list of password indexes is included at the end of this
  document.

  The coordinates of the starting position must be between 0 and 23,
  inclusive, otherwise it will appear as if there is a corridor in front of
  the player, but when they will try to move, they will hit a wall and will
  be surrounded by walls on all sides.

  A starting position may be pasted from a layout with the "Paste from
  layout" button.

*** IPS patch resources ***

  An IPS patch may replace any data in the ROM. The purpose of IPS patches is
  to provide a convenient way to modify the game's code and data which
  InsmEdit cannot patch. IPS patches are created with other programs and then
  imported into an Insmouse patch. Once an IPS patch is imported, InsmEdit
  can only apply it to a ROM or export it back to an IPS file.

  The index of an IPS patch cannot be changed and is currently always 0.

  IPS patches may not be larger than 32K. This limit is imposed by InsmEdit
  and the IMP file format. However, there is no limit to the number of IPS
  patches an IMP patch may contain.

*** Level time resources ***

  A level time resource specifies how much time the player has in a level to
  complete it (this is called "starting time") and how much time they must
  have remaining to advance to a "higher" level on the intermission screen
  (this is called "intense time").

  The index of a level time resource is the same as the index of a password
  resource. A list of password indexes is included at the end of this
  document.

  The times are specified in seconds. Both must be less than 600 seconds,
  otherwise the game will crash.

  When the amount of time left is equal to the intense time, the game will
  change the music and the player will enter the "lower" level on the
  intermission screen after finishing the level. The timer will start
  blinking when the amount of time left is thirty seconds or less (if the
  level starts with 30 seconds or less).

  The timer in the game will show one second less than specified. For
  example, if you specify a starting time of 599 seconds, it will show 9:58.

*** Music selection resources ***

  A music selection resource specifies which music track is played on a
  level.

  The index of a music selection resource is the same as the index of a
  password resource. A list of password indexes is included at the end of
  this document.

  Each music track has a number. There are 12 known music tracks. You can
  also type in the track number yourself, in case more tracks are discovered.
  Most other values, however, will crash the game.

*** Level monster resources ***

  A level monster resource specifies what monsters appear where in a level.

  The index of a level monster resource is the same as the index of a
  password resource. A list of password indexes is included at the end of
  this document.

  A level can only have one monster kind out of four, but the monsters can
  either be tall or short and dark or bright. Their size and shade affects
  their strength. Tall monsters can also break through "MWalls". No monster
  can go through doors.

  There can be up to 6 monsters in a level.

  A monster starting position may be pasted from a layout with the "Paste
  from layout" button.

  Note:
  If you remove a level monster resource from a patch and then apply the
  patch to a ROM to which you have applied a level monster resource before,
  strange things might happen because InsmEdit will not restore the original
  monster list. You should therefore always make a new copy of the original
  ROM before applying a patch from which you have removed a level monster
  resource.

*** The patch description ***

  A patch may contain a description. The description may contain any text.
  You can use it to store comments, a background story, credits, etc. To view
  and edit it, choose "Description" from the File menu.

*** Applying a patch to a ROM ***

  By choosing "Patch ROM" from the File menu, you can apply the currently
  open patch to an Insmouse No Yakata ROM.

  You are advised to make a copy of the ROM and apply the patch to that.
  InsmEdit will not automatically make a copy for you because you may want to
  apply multiple patches to a ROM.

  Only unpadded ROMs can be patched. InsmEdit will check the ROM before
  patching.

*** Command line usage ***

  You can start InsmEdit and have it open a patch from the command line.
  Simply append the path and filename of the patch to the path and filename
  of InsmEdit:

    InsmEdit Example.imp

  You can also associate InsmEdit with the IMP file extension so that when
  you open an Insmouse patch file from Windows Explorer, it will start
  InsmEdit automatically.

*** Technical information ***

  This section describes where in the Insmouse No Yakata ROM the data which
  InsmEdit replaces is located and how it is formatted.

  All addresses are decimal and one-based. The equivalent zero-based address
  in hexadecimal follows in parantheses.

  * Layouts - 873065 (D5268)

    Each layout is 576 bytes long. The tiles are stored row-major and each
    tile is one byte long. The possible values are:

    1 - wall
    2 - corridor
    3 - door
    4 - exit
    5 - monster wall

    Other values appear to be treated as walls.

    To get the address of a layout by index, add the index multiplied by 576
    to the starting address.

  * Passwords - 267713 (415C0)

    Each password is a four-character ASCII string.

    To get the address of a password by index, add the index multiplied by 4
    to the starting address.

  * Starting positions - 872881 (D51B0)

    Each starting position is two bytes long. The first byte is the X
    coordinate and the second byte is the Y coordinate.

    To get the address of a starting position by index, add the index
    multiplied by 2 to the starting address.

  * Starting directions - 872973 (D520D)

    Each starting direction is a halfword. Valid values are:

    1 - up
    2 - down
    3 - right
    4 - left

    To get the address of a starting direction by index, add the index
    multiplied by 2 to the starting address.

  * Level times and music selections - 900321 (DBCE0)

    There are three halfwords for each level. The first is the starting time,
    the halfword is the intense time, and the last is the music selection.
    Both times are in seconds.

    To get the address by index, add the index multiplied by 6 to the
    starting address.

  * Monster kinds - 269085 (41B1C)

    There is one halfword for each level. Valid values are:

    0 - big-mouthed, small-eyed
    1 - big-eyed
    2 - monkey-faced (like in ROPE)
    3 - faceless (like in HYDE)

  * Monster lists - 269401 (41C58)

    Each monster is an 8-byte structure. The first byte specifies the size
    and shade of the monster:

    0 - tall, dark
    1 - tall, bright
    2 - short, dark
    3 - short, bright

    The purpose of the second byte is unknown. It could be the initial
    direction. The next two bytes are a halfword for the X coordinate, and
    the two after that a halfword for the Y coordinate. At the end are two
    padding bytes.

    The list is terminated with an entry with all values set to -1.

    InsmEdit does not modify monster lists directly; rather, it creates new
    lists and puts them one after another starting at (as of version 1.2)
    971489 (ED2E0).

  * Monster list pointers - 271441 (42450)

    For each level, there is a word with the absolute address of the monster
    list for that level. When applying a patch, InsmEdit changes these
    pointers to point to the new monster lists.

*** The IMP file format ***

  This section describes the IMP ("Insmouse patch") file format used by
  InsmEdit.

  All values are stored little endian unless specified otherwise.

  A patch begins with a header:

  3 * Identification, always the ASCII characters "IMP".
  1 * Format version. The version described here is version 0.
  2 * Length of description in bytes.
  ^ * Description; encoding is undefined (InsmEdit expects it to be 8-bit).
  1 * Number of resources.

  The header is followed by resources. Each resource has the format:

  1 * Kind:
      0 - level layout
      1 - level password
      2 - starting position
      3 - IPS patch
      4 - level times
      5 - level music selection
      6 - level monsters

      InsmEdit will only edit and apply to ROMs the kinds mentioned above.
      It will preserve resources of kinds it does not understand.

  1 * Index. A patch may contain multiple resources of the same kind with the
      same index, although this is only useful in the case of IPS patches.

  2 * Size:
      * Level layouts: 576.
      * Level passwords: 4.
      * Starting positions. 2 or 3 if it includes the direction.
      * IPS patches: the size of the IPS patch minus 8 because the "PATCH"
        and "EOF" bytes are removed.
      * Level times: 4.
      * Level music selections: 2.
      * Level monsters: 1 plus 4 times the number of monsters.
      
  ^ * Data:
      * Level layouts: same as in the ROM.
      * Level passwords: same as in the ROM.
      * Starting positions: the first two bytes are the same as in the ROM.
        If there is a third byte, it is the direction and is the same as in
        the ROM.
      * IPS patches: a copy of the imported IPS file (therefore big endian)
        without the "PATCH" and "EOF" bytes.
      * Level times: same as in the ROM.
      * Level music selections: same as in the ROM.
      * Level monsters: the first byte is the monster kind, all other bytes
        are the monsters, with the first byte being the size and shade, the
        second byte being reserved for the unknown value (currently always
        0), and the third and fourth bytes being the X and Y coordinates.

  Programs that work with IMP files should preserve resources they do not
  understand. This includes preserving the size. Version 1 of InsmEdit did
  not preserve the direction in a starting position resource if such a
  resource is opened for editing and saved due to a coding flaw. However, if
  the size of a resource is smaller than expected, the effect is undefined.

*** Credits ***

  InsmEdit was developed by Matej Horvat ("HorvatM").

  Web site:        http://matejhorvat.si/
  Electronic mail: matej.horvat@guest.arnes.si

  Special thanks to DogP for a forum post that made me want to figure out how
  the layouts worked:

  http://www.vr32.de/modules/newbb/viewtopic.php?post_id=9868#forumpost9868

  and to KR155E for his FAQ which helped in figuring out stuff:

  http://www.vr32.de/modules/games/?r004ff005

*** Layout indexes ***

   0 - ADAM
   1 - ALPS
   2 - AQUA
   3 - ARCH
   4 - BABY
   5 - BALL
   6 - BODY
   7 - BONE
   8 - BOOK
   9 - CAFE
  10 - CAKE
  11 - DARK
  12 - DOOR
  13 - EDEN
  14 - EROS
  15 - FAKE
  16 - FISH
  17 - FOOL
  18 - GAME
  19 - GOAL
  20 - GUTS
  21 - HAND
  22 - HIGH
  23 - HYDE
  24 - INCA
  25 - IRON
  26 - JAZZ
  27 - LOVE
  28 - MASK
  29 - MEAT
  30 - RAIN
  31 - ROAD
  32 - ROCK
  33 - ROPE
  34 - RUBY
  35 - SNOW
  36 - TANK
  37 - URAN
  38 - WALK
  39 - WAVE
  40 - WEAR
  41 - WILD
  42 - WINE
  43 - WING
  44 - WOOD
  45 - unknown, not a level
  46 - DEMO

*** Password indexes ***

  These indexes apply to all resources except layouts.

   0 - ROPE
   1 - ROAD
   2 - LOVE
   3 - ARCH
   4 - IRON
   5 - CAFE
   6 - RUBY
   7 - DOOR
   8 - URAN
   9 - AQUA
  10 - HIGH
  11 - WILD
  12 - MEAT
  13 - WINE
  14 - BODY
  15 - JAZZ
  16 - GAME
  17 - BOOK
  18 - BALL
  19 - GUTS
  20 - TANK
  21 - MASK
  22 - HAND
  23 - WING
  24 - ADAM
  25 - WOOD
  26 - WALK
  27 - WAVE
  28 - WEAR
  29 - CAKE
  30 - EROS
  31 - SNOW
  32 - RAIN
  33 - GOAL
  34 - FISH
  35 - BONE
  36 - BABY
  37 - INCA
  38 - FAKE
  39 - ALPS
  40 - ROCK
  41 - FOOL
  42 - EDEN
  43 - HYDE
  44 - DARK
  45 - DEMO

*** Level connection diagram ***

  This is copied from KR155E's FAQ.

                                                  [GOAL]-[ROCK]
                                                   /   \     \
                                        [WING]-[CAKE]   \     \
                                         /    \    \     \     |
                              [BODY]-[BOOK]    \  [FISH]-[FOOL]|  Ending A
                               /   \     \      \  /   \     \ | /
                    [AQUA]-[WILD]   \   [HAND]-[EROS]   \   [HYDE]
                     /   \     \     \   /   \     \     \   /   \
          [LOVE]-[ARCH]   \   [JAZZ]-[GAME]   \   [BONE]-[ALPS]   Ending B
           /   \     \     \   /   \     \     \   /   \     \   /
[ROPE]-[ROAD]   \   [DOOR]-[HIGH]   \   [ADAM]-[WOOD]   \  [EDEN]
           \     \   /   \     \     \   /   \     \     \   /   \
          [IRON]-[CAFE]   \   [WINE]-[BALL]   \   [WEAR]-[BABY]   Ending C
                     \     \   /   \     \     \   /   \     \   /
                    [RUBY]-[URAN]   \   [TANK]-[WALK]   \   [DARK]
                               \     \   /    \    \     \   / | \
                              [MEAT]-[GUTS]    \  [RAIN]-[INCA]|  Ending D
                                         \      \  /   \       |
                                        [MASK]-[WAVE]   \     /
                                                   \     \   /
                                                  [SNOW]-[FAKE]
